home *** CD-ROM | disk | FTP | other *** search
/ Acorn RISC PD-CD 1 / Acorn RISC PD-CD 1.iso / languages / dde / _pc / h / drawfdiag < prev    next >
Text File  |  1992-02-09  |  15KB  |  365 lines
  1. (* 
  2.  * Title:  drawfdiag.h
  3.  * Purpose: Processing of Draw format files (diagram level interface)
  4.  *
  5.  *)
  6.  
  7. (*
  8.  *
  9.  * This file defines the interface to the simplest version of the
  10.  * DrawFile module. It can read in files to diagrams and render them.
  11.  * There is no checking of whether we have overrun the end of the
  12.  * diagram.
  13.  *
  14.  * To read in Draw files, it is expected that the caller will do the
  15.  * work of the I/O themselves.
  16.  *
  17.  * To dispose of a diagram, the caller can just throw it away, ie,
  18.  * the module does not keep any hidden information about what
  19.  * diagrams it has seen.
  20.  *
  21.  * Note on returning errors: some calls return an offset to the bad data on
  22.  * an error. This is not necessarily the start of an object: it may be bad
  23.  * data part way through it. The offset is relative to the start of the
  24.  * diagram.
  25.  *
  26.  * The module cannot handle rectangle or ellipse objects. Use a path instead.
  27.  *)
  28.  
  29. #ifndef __drawfdiag_h
  30. #define __drawfdiag_h
  31.  
  32. #ifndef __os_h
  33. #include "os.h"
  34. #endif
  35.  
  36. #ifndef __flex_h
  37. #include "flex.h"
  38. #endif
  39.  
  40. (********************************* Data types ******************************)
  41.  
  42. (*
  43.  * Type for a diagram: it consists of a pointer to the data and a
  44.  * length field. The length must be an exact number of words, and is
  45.  * the amount of space used in the diagram, not the size of the
  46.  * memory allocated to it.
  47.  *)
  48. type draw_diag_ptr = ^draw_diag;
  49.      draw_diag =
  50.        record
  51.          data : pointer;
  52.          length : integer
  53.        end;
  54.  
  55.  
  56. (* --- Abstract handle for an object --- *)
  57. (* The object handle is an offset from the start of the diagram to the
  58.  * object data.  You may use it to set a pointer directly to an object, 
  59.  * when using the object level interface
  60.  *)
  61. type draw_object_ptr = ^draw_object;
  62.      draw_object = integer;
  63.  
  64. (* --- Rectangular box: bounding boxes, etc. --- *)
  65. type draw_box_ptr = ^draw_box;
  66.      draw_box =
  67.        record
  68.          x0, y0, x1, y1 : integer
  69.        end;
  70.  
  71. (* --- Redraw structure: similar to a wimp_redrawstr --- *)
  72.  
  73. type draw_redrawstr_ptr = ^draw_redrawstr;
  74.      draw_redrawstr =
  75.        record
  76.          reserved : integer;
  77.          box : draw_box;         (* Work area box (x0, y1 used) *)
  78.          scx, scy : integer;     (* Scroll positions *)
  79.          g : draw_box            (* Graphics window box *)
  80.        end;
  81.  
  82.  
  83. (* Error type.
  84.  * Where a routine can produce an error, the actual value returned is a BOOL,
  85.  * which is TRUE if the routine succeeded. The error itself is returned in a
  86.  * block passed by the user; if NULL, then the details of the error are not
  87.  * passed back.
  88.  * The error block may contain either an operating system error, or an
  89.  * internal error. In the latter case, it consists of a code and possibly a
  90.  * pointer to the location in the file where the error occurred (if NULL,
  91.  * the location is not known or not specified). By convention, this should
  92.  * be reported by the caller in the form '<message> (location &xx in file)'.
  93.  * For a list of codes and standard errors, see h.DrawErrors. The location is
  94.  * relative to the start of the data block in the diagram.
  95.  *
  96.  *)
  97.  
  98. const DrawOSError = 0;
  99.       DrawOwnError = 1;
  100.  
  101. type draw_error_tag = DrawOSError..DrawOwnError;
  102.      draw_error_ptr = ^draw_error;
  103.      draw_error =
  104.        record
  105.          case _type : draw_error_tag of
  106.            DrawOSError  : (os : os_error);
  107.            DrawOwnError : (error :
  108.                              record
  109.                                code : integer;
  110.                                location : integer
  111.                              end)
  112.        end;
  113.  
  114.  
  115. (*----------------------------- Macros ---------------------------*)
  116.  
  117. (* Macros for unit conversion between Draw units and screen units *)
  118.  
  119. #define draw_drawToScreen(i) shr(i, 8)
  120. #define draw_screenToDraw(i) shl(i, 8)
  121.  
  122. (****************************** Function declarations **********************)
  123.  
  124.  
  125. (* ------------------------- draw_verify_diag ------------------------------
  126.  * Description:   Verifies a diagram which has been read in from file
  127.  *
  128.  * Parameters:    draw_diag *diag -- the diagram to be verified
  129.  *                draw_error *error -- the first error encountered (if any)
  130.  * Returns:       True if diagram is correct.
  131.  * Other Info:    Each object in the file is checked and the first error
  132.  *                encountered causes return (with error set appropriately)
  133.  *
  134.  *)
  135. function draw_verify_diag(diag : draw_diag_ptr;
  136.                 var error : draw_error) : boolean; extern;
  137.  
  138.  
  139. (* ------------------------- draw_append_diag ------------------------------
  140.  * Description:   Merges two diagrams into one.
  141.  *
  142.  * Parameters:    draw_diag *diag1 -- diagram to which to append diag2
  143.  *                draw_diag *diag2 -- diagram to be appended to diag1
  144.  *                draw_error *error -- possible error condition.
  145.  * Returns:       True if merge was successful.
  146.  * Other Info:    Both diagrams should have been processed by
  147.  *                draw_verify_diag(). Diag1's data block must be at least
  148.  *                diag1.length+diag2.length. Diag1.length will be updated
  149.  *                to its new appropriate value. Diag1's bounding box will
  150.  *                be set to the union of the bounding boxes of the two
  151.  *                diagrams. NOTE: offsets of objects in diag1 may change
  152.  *                due to a change in font table size (if diag2 has fonts).
  153.  *                Errors referring to specific locations, refer to diag2.
  154.  *
  155.  *)
  156. procedure draw_append_diag(diag1, diag2 : draw_diag_ptr;
  157.                 var error : draw_error) : boolean; extern;
  158.  
  159.  
  160. (* -------------------------- draw_render_diag -----------------------------
  161.  * Description:   Render a diagram with a given scale factor, in a given
  162.  *                WIMP redraw rectangle
  163.  *
  164.  * Parameters:    draw_diag *diag -- the diagram to be rendered
  165.  *                draw_redrawstr *r -- the WIMP redraw rectangle
  166.  *                double scale -- scale factor
  167.  *                draw_error *error -- possible error condition
  168.  *
  169.  * Returns:       True if render was successful
  170.  * Other Info:    The diagram must have been processed by
  171.  *                draw_verify_diag(). Note that draw_redrawstr is the same
  172.  *                as wimp_redrawstr, which may be cast to it.
  173.  *                Very small and negative scale factors will result in a
  174.  *                run-time error (safe > 0.00009). The caller should do
  175.  *                range checking on the scale factor.
  176.  *                Note: following the normal convention for coordinate
  177.  *                mapping, the part of the diagram rendered is found by
  178.  *                mapping the top left of the diagram, in draw coord space
  179.  *                onto a point:
  180.  *                   (r->box.x0 - r->scx, r->box.y1 - r->scy)
  181.  *                in screen coordinates.
  182.  *
  183.  *)
  184. procedure draw_render_diag(diag : draw_diag_ptr;
  185.                 r : draw_redrawstr_ptr;
  186.                 scale : real;
  187.                 var error : draw_error) : boolean; extern;
  188.  
  189.  
  190. (************************** Memory allocation functions ********************)
  191.  
  192. type draw_allocate = ^function allocate(anchor : flex_ptr;
  193.                                         n : integer) : integer;
  194.      draw_extend = ^function extend(anchor : flex_ptr;
  195.                                     n : integer) : integer;
  196.      draw_free = ^procedure free(anchor : flex_ptr);
  197.  
  198.  
  199. (* ---------------------- draw_registerMemoryFunctions ---------------------
  200.  * Description:   Register three functions to be used to allocate, extend
  201.  *                and free memory, when rendering text objects
  202.  *
  203.  * Parameters:    draw_allocate alloc -- pointer to function to be used for
  204.  *                                       memory allocation
  205.  *                draw_extend extend  -- pointer to function to be used for
  206.  *                                       memory extension
  207.  *                draw_free   free    -- pointer to function to be used for
  208.  *                                       memory freeing.
  209.  * Returns:       void.
  210.  * Other Info:    These three functions will be used only when rendering text
  211.  *                area objects. Any memory allocated during rendering will
  212.  *                be freed (using the supplied function) after rendering.  
  213.  *                If draw_registerMemoryFunctions() is never called,
  214.  *                or if memory allocation fails, then an attempt to render
  215.  *                a text area will produce no effect.
  216.  *                The three functions should operate as follows:
  217.  *                  int alloc(void **anchor, int n) : 
  218.  *                          allocate n bytes of store and set *anchor
  219.  *                          to point to them.
  220.  *                          Return 0 if store can't be allocated, otherwise
  221.  *                          non-zero.
  222.  *                  int extend (void **anchor, int n):
  223.  *                          extend the block of memory which starts at 
  224.  *                          *anchor to a total size of n bytes. Note that
  225.  *                          n will always be positive, and the new memory
  226.  *                          should be appended to the existing block (which
  227.  *                          may be moved by the operation).
  228.  *                          Return 0 if the memory can't be allocated, else
  229.  *                          non-zero.
  230.  *                  void free(void **anchor):
  231.  *                          free the block of memory which starts at
  232.  *                          *anchor, and set *anchor to 0.
  233.  *
  234.  *                **NOTE** : The specification for these three functions is
  235.  *                           the same as that for flex_alloc, flex_extend
  236.  *                           and flex_free (in the flex module), so these
  237.  *                           can be used as the three required functions!!
  238.  *
  239.  *)
  240. procedure draw_registerMemoryFunctions(alloc : draw_allocate;
  241.                                        extend : draw_extend;
  242.                                        free : draw_free); extern;
  243.  
  244.  
  245. (* -------------------------- draw_shift_diag ------------------------------
  246.  * Description:   Shift a diagram by a given distance.
  247.  *
  248.  * Parameters:    draw_diag *diag -- the diagram to be shifted
  249.  *                int xMove -- distance to shift in x direction
  250.  *                int yMove -- distance to shift in y direction.
  251.  * Returns:       void.
  252.  * Other Info:    All coordinates in the diagram are moved by the given
  253.  *                distance.
  254.  *
  255.  *)
  256. procedure draw_shift_diag(diag : draw_diag_ptr;
  257.                 xMove, yMove : integer); extern;
  258.  
  259.  
  260. (* ---------------------------- draw_querybox ------------------------------
  261.  * Description:   Find the bounding box of a diagram.
  262.  *
  263.  * Parameters:    draw_diag *diag -- the diagram
  264.  *                draw_box *box  -- the returned bounding box
  265.  *                BOOL screenUnits -- indication whether the box is to be
  266.  *                                    specified in draw or screen units.
  267.  * Returns:       void.
  268.  * Other Info:    The bounding box of diag is returned in box. If 
  269.  *                screenUnits is true, box is in screen units, else in draw
  270.  *                units.
  271.  *
  272.  *)
  273. procedure draw_queryBox(diag : draw_diag_ptr;
  274.                 box : draw_box_ptr;
  275.                 screenUnits : boolean); extern;
  276.  
  277.  
  278. (* ----------------------------- draw_convertBox ---------------------------
  279.  * Description:   Convert a box to/from screen coordinates.
  280.  *
  281.  * Parameters:    draw_box *from -- box to be converted
  282.  *                draw_box *to   -- converted box.
  283.  *                BOOL toScreen  -- should set to TRUE if conversion is to
  284.  *                                  be from draw coords to screen coords
  285.  *                                  FALSE means from screen coords to draw
  286.  *                                  coords.
  287.  * Returns:       void.
  288.  * Other Info:    from and to may point to the same box.
  289.  *
  290.  *)
  291. procedure draw_convertBox(from : draw_box_ptr;
  292.                 _to : draw_box_ptr;
  293.                 toScreen : boolean); extern;
  294.  
  295.  
  296. (* --------------------------- draw_rebind_diag ----------------------------
  297.  * Description:   Force the header of a diagram's bounding box to be exactly
  298.  *                the union of the objects in it.
  299.  *
  300.  * Parameters:    draw_diag *diag -- the diagram.
  301.  * Returns:       void.
  302.  * Other Info:    The diagram should have been processed by
  303.  *                draw_verify_diag() first.
  304.  *
  305.  *)
  306. procedure draw_rebind_diag(diag : draw_diag_ptr); extern;
  307.  
  308.  
  309.  
  310. (************************ Unknown object handling **************************)
  311.  
  312. (* 
  313.  * New types of object can be added by registering an unknown object handler.
  314.  * The handler is called whenever an attempt is made to render an object 
  315.  * whose tag is not one of the standard ones known to DrawFile. It is passed
  316.  * a pointer to the object to be rendered (cast to a pointer), and a pointer
  317.  * to a block into which to write any error status. The object pointer may
  318.  * be cast to one of the standard Draw types (defined in the object level
  319.  * interface), or to a client-defined type. If an error occurs, the handler
  320.  * must return FALSE and set up the error block; otherwise it must return
  321.  * TRUE. Unknown objects must conform to the standard convention for object
  322.  * headers, i.e. 1-word object tag; 1-word object size; 4-word bounding box.
  323.  * The unknown object handler is only called if the object is visible, i.e.
  324.  * if there is an overlap between its bounding box and the region of the
  325.  * diagram being rendered. The object size field must be correct, otherwise
  326.  * catastrophes will probably result. 
  327.  *
  328.  *)
  329.  
  330. (* Type for unknown object handler *)
  331. type draw_unknown_object_handler = ^function handler(object : pointer;
  332.                                         handle : pointer;
  333.                                         var error : draw_error) : boolean;
  334.  
  335.  
  336. (* ------------------------ draw_set_unknown_object_handler ----------------
  337.  * Description:   Registers a function to be called when an attempt is made
  338.  *                to render an object with an object tag which is not known
  339.  *                
  340.  * Parameters:    draw_unknown_object_handler handler -- the handler function
  341.  *                void *handle -- arbitrary handle to pass to function
  342.  * Returns:       The previous handler.
  343.  * Other Info:    The handler can be removed by calling with 0 as a 
  344.  *                parameter.
  345.  *
  346.  *)
  347. function draw_set_unknown_object_handler(
  348.                 handler : draw_unknown_object_handler;
  349.                 handle : pointer) : draw_unknown_object_handler; extern;
  350.  
  351.  
  352. (* ------------------------- drawfdiag_init --------------------------------
  353.  * Description:   Initialise the diagram level interface
  354.  *
  355.  * Parameters:    void
  356.  * Returns:       TRUE if all went OK.
  357.  * Other Info:    none
  358.  *
  359.  *)
  360. function drawfdiag_init : boolean; extern;
  361.  
  362. #endif
  363.  
  364. (* end drawfdiag.h *)
  365.